fix(driver-memory): analytics honours the declared AnalyticsQuery.timezone when resolving a string dateRange (#16042) - #16174

Fixes #16042

packages/drivers/driver-memory/src/memory-analytics.ts declared AnalyticsQuery.timezone on its way in and never read it, so dateRange: 'today' was answered on the UTC calendar for a caller who had said which calendar they meant. Direction chosen: the driver HONOURS the field.

Why honour it rather than stop advertising it

The card states the choice as binary — honour it, or stop advertising it on this path — and "a third state where it is accepted and ignored is the one that misleads." Stopping the advertisement is not available to this card, and not merely by dispatch fence:

• The declaration lives in packages/spec/src/data/analytics.zod.ts, another lane this card does not edit.
• Withdrawing it at the driver would mean REFUSING a query that carries timezone, which every current caller passes legitimately — service-analytics' buildQuery writes a timezone into every AnalyticsQuery it builds (selection.timezone ?? contextTimezone ?? 'UTC', dataset-executor.ts:1121). A refusal there would reject the platform's own normal traffic.

So the repair is agreement, and the driver owes the last two links of the declared chain: the value it was handed, else UTC.

Before / after row sets — a non-UTC zone

Asia/Shanghai, clock frozen at 2026-09-06T20:00:00Z (04:00 on 2026-09-07 in Shanghai), dateRange: 'today', eight probe rows. Both row sets are asserted against the real MemoryAnalyticsService.query() entry in the same test, so the "before" is measured, not recalled.

Four rows either way, two of the four different: 06T00:00:00.000Z and 06T15:59:59.999Z leave (yesterday in Shanghai), 07T04:00:00.000Z and 07T15:59:59.999Z join (today in Shanghai). This is the change the card warned is not a drive-by.

A query carrying no timezone is unchanged by construction, and #15825's two pins stay green (52 tests across the three date-range files).

The repair has two halves and each fails silently alone

1. WHICH calendar day 'today' is — calendarPartsInTzOrUtc(now, tz), then arithmetic on a UTC proxy day (the proxyDay() pattern in packages/core/src/utils/filter-tokens.ts:167).
2. WHERE that day begins as an instant — zonedDateStartToUtcMs(ymd, tz), that zone's local midnight.

Half 2 is required because the bounds here are rendered with toISOString() and compared against datetime values. That is exactly the case ADR-0053 already settles, in the only other place in this tree that turns a reference timezone into an instant bound — packages/services/service-analytics/src/analytics-service.ts:1271-1302: const rangeTz = selection.timezone ?? context?.timezone ?? 'UTC', then "datetime → the reference tz's MIDNIGHT INSTANT (ISO), because the bucket is defined on that tz's calendar", with the bare YYYY-MM-DD calendar bound reserved for a date-typed, tz-naive column.

⛔ Half 1 alone is a silent wrong answer, and the pin proves it: see ablation B below, where Asia/Kolkata degenerates to exactly the UTC row set.
⛔ The end bound is a calendar step, never + 86_400_000: on America/New_York, 2026-03-08 begins at 05:00Z and 2026-03-09 at 04:00Z — a 23-hour day.

Anchors and real line numbers (at 1328902ce)

The card's own re-check recipe self-falsifies — re-checked correctly

The card says git grep -n 'timezone' -- .../memory-analytics.ts → 0 hits (at 2024eca4f). Today it returns 5, and all five are comments added by #15825, one of them literally "⚠️ Out of scope here, filed separately" pointing at this card. Re-checked by searching for a READ instead: git grep -nE "\.timezone|timezone\s*[:)]" hit only those same two comment lines; control dateRange = 4 in the same file, so the grep fires. Zero reads confirmed.

Verification

• Pin: 14 cases over 7 zones — both offset signs, three non-whole-hour offsets (Kolkata +05:30, Chatham +12:45), both tz-database extremes (Kiritimati +14:00, Niue −11:00), one cell sharing UTC's calendar day, and one 23-hour spring-forward day. Every window literal was computed independently of the code under test, from Intl.DateTimeFormat alone.
• Suites: pnpm --filter @objectstack/driver-memory exec vitest run over the new pin + memory-analytics-date-range-utc-window + memory-analytics-date-range-dst + memory-analytics — 74 passed / 74.
• Ablation A (remove the timezone read at the call site): 9 failures, all in the new pin; driver-memory analytics parseDateRangeString() builds its window on the LOCAL calendar and renders it as UTC — 'today' and 'last N days' are offset by the process timezone in every non-UTC zone #15825's two pins stayed green — the new pin does not overlap their territory. Mutation proved on disk (blob e2a48c2f → be1295d0); restore proved (blob back to the HEAD blob, git diff HEAD empty).
• Ablation B (proxyDay()-only — resolve the day in the zone, cut it at UTC midnight): 9 failures. Asia/Kolkata returned [06T00:00:00.000Z … 06T23:59:59.999Z] — the UTC day exactly, which is what makes half 2 load-bearing rather than decorative. Mutation and restore proved the same way.
• Gates: all 54 families derived by node scripts/pm/dispatch-gates.mjs --repo objectstack-ai/objectstack (43 by path + 6 by change kind + 7 whole-tree, 2 reached both ways), run with redirect-then-read at head 1328902ce — 54/54 exit 0. The anchor/census family is included because this diff changes line counts: check-system-context-census reports "105 elevation read sites … all anchored; 140 anchors resolve". check:dts-closure swept 71 built packages and packages/drivers/driver-memory/dist/index.d.ts exists, so its green is a statement about this package.

Clause ② — no, re-derived from this diff

Instrument: build at head → revert memory-analytics.ts to origin/main → rebuild (tsup directly, no turbo cache on the path) → diff every file files[] publishes → restore byte-exact. Rebuild proved by mtime movement (index.d.ts 1788667498 → 1788668359 → 1788668363) with the .js hash genuinely changing between snapshots.

⛔ The byte-identical declaration is not taken on faith — the two known false negatives were excluded by measurement, not by shape:

• Not a barrel: dist/index.d.ts is 1031 lines with 23 export/declare lines and 0 re-export-only lines. Firing control: MemoryAnalyticsService appears 5× in it.
• No shared chunk: dist/ is exactly 6 files, all index.*. There is no chunk for a member to hide in.
• Why it is identical, mechanically: the only edited member is private parseDateRangeString, and TypeScript emits a private member as a bare name with no signature — private parseDateRangeString; at dist/index.d.ts:769, identical line and position in both snapshots. The added parameter is invisible to the declaration by construction.
• The new test file reaches no published artefact: both sourcemaps list 11 sources, 0 of them .test./.spec., and neither names date-range-timezone.

Limb 2 — is any request newly accepted or rejected? No. AnalyticsQuerySchema is untouched, so every query that parsed before parses now. The driver adds no refusal path, no new error code and no new throw: both primitives degrade an unset, 'UTC', or unknown zone to UTC rather than raising (measured live — Mars/Olympus yields UTC parts and UTC midnight), and the pin asserts a bogus zone still returns an answer. A query that was answered with UTC rows and is now answered with Shanghai rows is a change to the value returned for an accepted request, not to the accept set — which is why this needs a minor changeset and the before/after table above, and is still a clause-② no.

Docs drift — run by hand, because the check declares itself blind here

Docs Drift Check returned "nothing to list"; that is not a clean bill of health, so I ran the tool and then hand-searched. node scripts/docs-audit/affected-docs.mjs --json <merge-base> on a clean tree (dirty: false, head 1328902ce, base 94ecb7e5c) says: anchors = exactly one, parseDateRangeString (symbol, a method of MemoryAnalyticsService); docs = []; anchorlessChanges = []; overbroadAnchors = []; testFilesSkipped = 1. ⭐ weakAnchorsDropped = ["query (symbol)"] — the name too generic to anchor is query, the public method whose body carries the changed call site. It is not timezone, which is the guess this shape invites.

Hand-search of content/docs (plain directory pathspec; 190 hand-written .mdx outside content/docs/references/**), since the check sees only pages that NAME an anchor:

• No page documents the timeDimensions[].dateRange relative-token vocabulary at all. dateRange appears in 5 hand-written pages, none about this path; the three analytics pages (data-modeling/analytics.mdx, capabilities/analytics.mdx, ui/reports.mdx) contain 0 occurrences of dateRange, timezone, UTC, timeDimension or calendar — with firing controls on each (analytics → 8 / 1 / 10).
• The rule-by-its-INPUTS shape, checked deliberately: content/docs/ui/dashboards.mdx is the one page that names range tokens (today, this_month, last_7_days, {today}, {30_days_ago}). It makes no calendar claim whatsoever — utc 0, timezone 0, time zone 0, calendar 0 in that file (control: today → 2). So there is nothing there for this change to falsify. Its vocabulary is also a different one: dashboard presets are underscored (last_7_days) and {today} is a core filter-token macro, whereas this path parses spaced strings ('last 7 days').
• Negative claims that would be falsified: twelve phrasings searched (always UTC, always resolved in UTC, interpreted as UTC, ignores timezone, UTC-only, …) → 0 hits each, against a firing control (UTC → 35 hand-written pages). The 4 not honou hits are MySQL upsert, email transport and boot assertions — unrelated.
• The one live UTC claim, and why it survives: content/docs/data-modeling/queries.mdx:668-673 says "Buckets are computed in UTC. A non-UTC reference timezone is only reachable through ObjectQL.aggregate(object, { …, timezone })". That is scoped to groupBy / dateGranularity bucketing on the ObjectQL path — a different path from the cube timeDimensions[].dateRange window this PR changes. Measured support rather than asserted: git grep -n granularity -- packages/drivers/driver-memory/src/memory-analytics.ts returns 0 — MemoryAnalyticsService does no bucketing at all. Not falsified, and not edited.
• The midnight UTC claims in protocol/objectql/query-syntax.mdx and data-modeling/queries.mdx are ADR-0053's bare-YYYY-MM-DD whole-day rule for filter comparands. Untouched: nextUtcCalendarDay still returns null for a full ISO timestamp, so the widening rule is unchanged.

⇒ No documentation edit is owed by this PR, and nothing under content/docs/releases/** was touched. The real gap the drift check is pointing at is that this vocabulary is undocumented — reported to the PM rather than fixed here, since writing that page is not this card.

Scope

• ⛔ driver-memory analytics parseDateRangeString() builds its window on the LOCAL calendar and renders it as UTC — 'today' and 'last N days' are offset by the process timezone in every non-UTC zone #15825 is not re-opened or redone. It made this path agree with the chain's terminal … ?? 'UTC' for every query carrying no timezone; this card is only the remaining supplied-timezone case. Its one now-narrower sentence was scoped in place, not rewritten.
• ⛔ packages/spec is not edited.
• driver-memory analytics silently accepts an unparseable dateRange and matches EVERY row — and the platform's own documented spelling 'Last 7 days' is one of them #16041 — read it, it is not what a one-line summary of it suggests. It is titled "driver-memory analytics silently accepts an unparseable dateRange and matches EVERY row", and it carries bug · priority:p2 · needs-user-decision · domain:engine. The token-vocabulary-sharing question is one of its three open questions, not the whole of it. That matters here because driver-memory analytics silently accepts an unparseable dateRange and matches EVERY row — and the platform's own documented spelling 'Last 7 days' is one of them #16041's defect lives in the same function this PR edits: the return [range, range] fallback for an unrecognised string.
  • This PR does not touch that fallback. The line is unchanged, and it returns before any of the new code runs — boundary() is invoked only inside the 'today' and 'last ' branches. The new resolution adds no throw on that path either: calendarPartsInTzOrUtc and zonedDateStartToUtcMs both degrade an unknown zone to UTC rather than raising.
  • On the vocabulary question it does raise, this fix makes sharing more attractive without deciding it: both paths now resolve the reference day through the same primitive and the same UTC-proxy rule, so the divergence is narrower. But it is real and not cosmetic — the filter-token macros emit a bare YYYY-MM-DD calendar day while this path emits an instant, and ADR-0053 gives those two different boundary rules on purpose. A shared vocabulary would have to carry that distinction, not erase it.
  • ⚠️ Whoever takes driver-memory analytics silently accepts an unparseable dateRange and matches EVERY row — and the platform's own documented spelling 'Last 7 days' is one of them #16041 must carry this timezone resolution into whatever replaces the parser — replacing parseDateRangeString wholesale would silently drop it again.

🤖 Generated with Claude Code

https://claude.ai/code/session_01ARYe3yQTQCUFm5qPYNgKaJ

Generated by Claude Code